=== About His ( Human interface service ) ===

His aims to translate an event in a given app to an event in a physical device.
this is done by detecting the color of one or more pixels and translate it to a mapped device.

the hope is that this will give a more immersive experience.


=== user interface ===

the user interface contains of a simple menu allowing the user to select wich configurations to use for this session
before starting input, output and mapping must be selected

depending on the input the user will then be able to detect or enter the required locations or just start if the location is already entered

changing configurations will require a restart

since input depends on pixel location it is vital that the app is not moved after detection, fullscreen makes it easier


=== Quick Start ===

if this is your first run and you just want to see it work, follow these steps
if you are just testing and you don't have a device yet, skip step 1 and stop after step 8

1. edit the output configuration ( depends on what device you have )
	open the output folder and open the "pyhs.json" file in notepad ( or your favorite json editor )
	change the ip to the ip of your tp link device
	save the file
2. run the file
	double click "His.exe"
3. open an image with a detectable input pixel
	double click "red.png" place the image on the screen so the red pixel is visable
4. select input
	click "red / green"
	when starting "Input" is already selected, if you clicked away from it, just click "Input" again
	try "Auto" if it does not find the location, use "Manuel" and click through the screenshot until the right pixel is selected
	click "Use"
5. select mapping
	click "Mapping" then click "console and pyhs"
6. select output
	click "Output" then click "console"
7. start
	click "Setting", click "Run when ready"
8. change state
	in your image viewer change to the next image ( in windows photos its the arrow key )
	the console text changes, if it does not refer to the troubleshooting at the end
10. select the output configuration
	click the "Output" menu button
	click "pyhs"
11. play
	change state like you did in step 8



=== Configuration ===

it is highly recommended to modify the existing configurations, rather than write new ones from scratch.

configuration falls into 3 groups
input: defines how input should be captured, and what inputs to expect from the app
output: defines what devices are available, what input they can handle, as well as any device specific configuration
mapping: this maps the input to the output

common to all configurations is that they use json, and they each have a name, names should be globally unique.
It might be neccersary to change the names if there is a clash


== input ==
input is mostly of interest to app developers, if you are a normal user you would normally just copy the configuration from the app

an input configuration defines a series of listeners, each can either attempt to detect the pixel location by defining a color to search for or it can define the location directly.
To the end user it is always best to have a predefined location, but this can be really hard to know if the app is not always in full screen.

each listener defines a series of states, with each having a name and a condition the actual input will be a list containing the satisfied conditions.
if no conditions are satisfied, the listener default will be used

there should be a special reason for using more than one listener

the default and state names should be unique for the given input file


== output ==

output configurations will typicall look like a simple key value list.
since they are specific for the device so will the documentatin be for each supported device

all output configurations have a name, and a handler. the following handlers are defined


= pyhs =
this is the handler for tp-link, testet on
TP-Link HS100 Wi-Fi Smart Plug
requires ip for the device, this can be found through the router the device is connected to


= console =
this is a test handler writing to the console when a state changes
requires no other fields

if you want the mapped input to be sent to multiple outputs, replace the "handler" with "outputs" containing a list of the names of the outputs to send to


== mapping ==

this is where the user defines how input is mapped to output
each mapping configuration contains a list of mappings.

there can be more than one mapping for a given input
since the state name in an input configuration is unique for that input and only one input can be selected at a time the input name is not needed
since more than one output configuration can be active the name of the output must be in each mapping


=== troubleshooting ===

Detect fails with "found 0"
	the pixel can not be found, make sure it is in a visible location on your screen

Detect fails with "found x" ( x > 0 )
	there are too many pixels found, the easiest way to get around this is to maximize the app you are searching in
